docs: refresh stale items vs current code; archive completed hosting record by slittycode · Pull Request #124 · slittycode/ableton-sonic-analyzer

slittycode · 2026-05-30T20:51:22Z

Summary

Doc-vs-code audit and refresh. Three parallel audit agents (root docs, docs/, per-app docs) compared the documentation surface against the current code; this PR fixes the stale items they flagged and archives one completed-work record. Markdown only — no code touched.

The two biggest themes:

MT3 polyphonic transcription shipped as an opt-in production stage (PR feat: optional MT3 polyphonic-transcription stage + interpretation grounding gate #122, commit b2df43a) but the doc inventories — backend AGENTS/ARCHITECTURE/README, UI AGENTS/README, CLAUDE.md frontend service list, and all three CHANGELOGs — were one feature behind. apps/backend/AGENTS.md even still contained guidance saying not to add MT3 as a production backend.
The "Unreleased" CHANGELOGs had fallen ~4 features behind. No entries for MT3, Live 12 catalogue + phase2_catalogue_gates, pianoroll endpoint + symusic consolidation, or the recommendation-proof campaign.

What changed

MT3: added to apps/backend/AGENTS.md (file map + corrected guidance), apps/backend/ARCHITECTURE.md (Components table + mt3-transcriptions route), apps/backend/README.md (Polyphonic section now reflects opt-in shipping), apps/ui/AGENTS.md + apps/ui/README.md (mt3Client.ts + UI surface), CLAUDE.md (new backend file entry, new frontend service entry, ASA_ENABLE_MT3 env var).
CHANGELOGs caught up: CHANGELOG.md, apps/backend/CHANGELOG.md, apps/ui/CHANGELOG.md all now have entries for MT3, Live 12 catalogue + gates, pianoroll + symusic, and the recommendation-proof campaign.
CLAUDE.md targeted fixes: wrong analysis_runtime.py:685 ref → ~L800; added ASA_SAMPLE_SYNTH_BACKEND to env vars; corrected the tsconfig.json exclude description (was missing vitest.config.ts); dropped the unreachable 5c40dd44 commit hash.
docs/ARCHITECTURE_STRATEGY.md + docs/POLYPHONIC_TRANSCRIPTION_SPIKE.md: reflect that MT3 has shipped as an opt-in additive stage; the offline harness remains the comparison rig for other candidates.
docs/SAMPLE_GENERATION.md: fix schematic synth_kit() to the real synth_kick/snare/hat() trio.
apps/backend/JSON_SCHEMA.md: annotate the shared-vs-full carve-out so the six full-mode-only top-level keys (keyProfile, tuningFrequency, tuningCents, lufsMomentaryMax, lufsShortTermMax, pitchDetail) are explicit against EXPECTED_TOP_LEVEL_KEYS (CLAUDE.md tripwire fix: chunk Demucs inference and stop boot-time memory spikes #4).
Archive: moved docs/PUBLIC_HOSTING_FOUNDATION.md → docs/history/public-hosting-foundation-2026-04-01.md with an archived-banner; it's a completion record, not a living spec. Updated inbound references in CHANGELOG.md, docs/SETUP.md, docs/history/README.md, and docs/history/archive/refactor-state-2026-03-18.md.
incorporations/forking-plans-2026-05-14.md: added a 2026-05-30 status update noting Plan 6 substantially landed via the Live 12 catalogue + gates work; Plans 4/5 stay open; Plans 7/8 remain re-scoped per the existing 2026-05-22 correction.
Refreshed as of 2026-05-27 date stamps in both per-app AGENTS.md files to 2026-05-30.

Test plan

Skim CLAUDE.md, apps/backend/AGENTS.md, apps/backend/ARCHITECTURE.md, apps/ui/AGENTS.md for tone — they're load-bearing onboarding docs and the edits should read naturally next to the surrounding text.
Sanity-check the MT3 entries against the actual code (route at server.py:3247, module at mt3_transcription.py, client at apps/ui/src/services/mt3Client.ts, env var at analyze.py:1851).
Verify the docs/history/public-hosting-foundation-2026-04-01.md archive banner is visible and that the inbound links in CHANGELOG.md, docs/SETUP.md, and docs/history/README.md resolve.
Confirm no code paths reference the old docs/PUBLIC_HOSTING_FOUNDATION.md path (audit confirmed: only the three markdown references above; all updated).
Quick scan of the three CHANGELOG.md Unreleased sections for chronological ordering / consistency with prior entries.

https://claude.ai/code/session_016m6cUFNwb3kD2EzAbgqCHe

Generated by Claude Code

…record Sweep against the 2026-05-30 audit findings — the doc surface had drifted through the MT3, Live 12 catalogue, pianoroll/symusic, and recommendation-proof merges. Adds those features to the inventories where they were missing, fixes a wrong line reference, removes a dead commit hash, refreshes date stamps, and archives a completed-work record. - MT3 polyphonic transcription: add to apps/backend/AGENTS.md (file map + guidance), apps/backend/ARCHITECTURE.md (Components table + mt3-transcriptions route), apps/backend/README.md (Polyphonic section now reflects opt-in shipping), apps/ui/AGENTS.md + apps/ui/README.md (mt3Client.ts + UI surface), CLAUDE.md (#19 backend file, #6a frontend service), and all three CHANGELOG.md files. - Live 12 catalogue + phase2_catalogue_gates, transcription pianoroll + symusic, recommendation-proof campaign: add to CHANGELOG.md (root) and apps/backend/CHANGELOG.md and apps/ui/CHANGELOG.md. - CLAUDE.md: fix wrong analysis_runtime.py line ref (685 → ~800), add ASA_ENABLE_MT3 and ASA_SAMPLE_SYNTH_BACKEND env vars, correct the tsconfig excludes description, drop the unreachable 5c40dd4 commit hash. - apps/backend/AGENTS.md + ARCHITECTURE.md: drop the same dead 5c40dd4 hash. - docs/ARCHITECTURE_STRATEGY.md + docs/POLYPHONIC_TRANSCRIPTION_SPIKE.md: reflect that MT3 has shipped as an opt-in, additive stage (the spike harness remains the offline comparison rig for other candidates). - docs/SAMPLE_GENERATION.md: fix the schematic node label (synth_kit() → the real synth_kick/snare/hat() trio). - apps/backend/JSON_SCHEMA.md: annotate the shared-vs-full carve-out so the full-mode-only keys (keyProfile, tuningFrequency, tuningCents, lufsMomentaryMax, lufsShortTermMax, pitchDetail) are explicit per CLAUDE.md tripwire #4. - Archive docs/PUBLIC_HOSTING_FOUNDATION.md → docs/history/public-hosting-foundation-2026-04-01.md with an archived-banner; update inbound references in CHANGELOG.md, docs/SETUP.md, docs/history/README.md, and docs/history/archive/refactor-state-2026-03-18.md. - incorporations/forking-plans-2026-05-14.md: add a 2026-05-30 status update noting Plan 6 substantially landed via the Live 12 catalogue + gates work. No code touched — markdown only. https://claude.ai/code/session_016m6cUFNwb3kD2EzAbgqCHe

slittycode

Verdict: APPROVE (posted as COMMENT — can't self-approve)

Summary

Pure docs refresh — 18 markdown files, zero code touched. The PR catches up three CHANGELOGs and multiple AGENTS/ARCHITECTURE/README files to reflect features that shipped in PR #122 (MT3 opt-in stage, Live 12 catalogue + gates, pianoroll endpoint, recommendation-proof campaign). Also archives docs/PUBLIC_HOSTING_FOUNDATION.md → docs/history/public-hosting-foundation-2026-04-01.md with all inbound links updated. No automated tests are applicable; nothing here can break the runtime.

Findings

Worth considering (one item):

docs/history/public-hosting-foundation-2026-04-01.md archive banner says "the 'Remaining work before real public hosting' section near the end is the live punch list and lives outside this archived doc" — but that section is in the archived doc, not outside it. The docs/history/README.md entry is clearer ("punch list inside is aspirational — re-open items in BACKLOG.md if needed"). The banner phrasing is contradictory. Not a blocker; a one-word tweak ("is aspirational — re-open in BACKLOG.md") would clear it up.

Everything else checks out:

MT3 entries are internally consistent across all six touched docs: opt-in, additive, mt3_mode='enabled' canonical gate, ASA_ENABLE_MT3=1 legacy CLI gate, never overrides measurement.
The analysis_runtime.py:685 → ~L800 line-number fix is correct.
The vitest.config.ts tsconfig exclude addition is accurate.
synth_kit() → synth_kick/snare/hat() schematic fix is correct.
Both link fixes in docs/history/archive/refactor-state-2026-03-18.md are correct: ../ARCHITECTURE_STRATEGY.md was broken (resolved to non-existent docs/history/ARCHITECTURE_STRATEGY.md), now fixed to ../../ARCHITECTURE_STRATEGY.md; hosting-foundation link updated to match the rename.

Test results

N/A — docs-only PR.

Phase boundary check

Clean. No code changes.

Generated by Claude Code

The banner said the "Remaining work" section "lives outside this archived doc" but that section is in the doc itself. Aligns with the clearer phrasing already used in docs/history/README.md. https://claude.ai/code/session_016m6cUFNwb3kD2EzAbgqCHe

slittycode

Verdict: APPROVE (posted as COMMENT — GitHub blocks self-review)

Summary

Docs-only PR that catches the doc surface up to four features that shipped in the last sprint (MT3, Live 12 catalogue + gates, transcription pianoroll, recommendation-proof campaign), fixes two genuinely broken relative links, and archives a completed hosting-foundation doc. No code changed. Every factual claim was verified against the actual code and all check out.

Verified against code:

mt3Client.ts, mt3_transcription.py, test_mt3_transcription.py all exist
transcriptionDetail strip is at analysis_runtime.py:800 — ~L800 is accurate
vitest.config.ts is in tsconfig.json exclude — the lint guardrail note is now correct
synth_kick/snare/hat() are the real function names; synth_kit() was wrong
ASA_ENABLE_MT3 at analyze.py:1851, _execute_mt3_attempt/_mt3_worker_loop in server.py, MT3 route at server.py:3247 — all match
ASA_SAMPLE_SYNTH_BACKEND env var confirmed in sample_synthesis.py
Path fix in docs/history/archive/refactor-state-2026-03-18.md (../ARCHITECTURE_STRATEGY.md → ../../ARCHITECTURE_STRATEGY.md) corrects a link that was already broken before this PR

Findings

Worth considering:

CLAUDE.md frontend services list inserts 6a. between items 6 and 7 rather than renumbering 7–17 to 7–18. Markdown renders it literally so it reads fine, but the mixed numbering is mildly confusing for anyone scanning that list. Avoids a noisy renumber diff, so defensible as-is.

That's it. Nothing blocking.

Test results

N/A — docs-only, no code changed.

Phase boundary check

Clean. No source files touched.

Generated by Claude Code

slittycode commented May 30, 2026

View reviewed changes

slittycode merged commit 4c5359e into main May 31, 2026
4 checks passed

slittycode deleted the claude/gifted-cerf-WCkel branch May 31, 2026 14:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: refresh stale items vs current code; archive completed hosting record - #124

docs: refresh stale items vs current code; archive completed hosting record#124
slittycode merged 2 commits into
mainfrom
claude/gifted-cerf-WCkel

slittycode commented May 30, 2026

Uh oh!

slittycode left a comment

Uh oh!

slittycode left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

slittycode commented May 30, 2026

Summary

What changed

Test plan

Uh oh!

slittycode left a comment

Choose a reason for hiding this comment

Verdict: APPROVE (posted as COMMENT — can't self-approve)

Summary

Findings

Test results

Phase boundary check

Uh oh!

slittycode left a comment

Choose a reason for hiding this comment

Verdict: APPROVE (posted as COMMENT — GitHub blocks self-review)

Summary

Findings

Test results

Phase boundary check

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants